docs: document the command boundary and spec its public surface - #28

The @moduledoc was still the placeholder `mix new` writes and none of
the commands carried a @doc or a @SPEC, so the published page said
nothing about the one thing a reader has to know before calling any of
it: these are not an Elixir API. Every function but `customize/1` is a
command entry point that `bin/castle` reaches over `rpc` - it prints its
report and returns a bare `:ok`, and it raises `Castle.Error` on failure
so that the calling VM exits non-zero. A reader who takes them for
ordinary functions is surprised by both halves, so the moduledoc says
what a command boundary is and every @doc names the `bin/castle` command
that reaches it. castle#11.

The distinction the issue asked to be settled, settled deliberately:

  * `make_releases/0` is @doc false. Its only caller is the launcher's
    `env.sh` fragment, in the preboot VM of a start whose deployment has
    no `RELEASES` yet, and by hand it either does nothing or does what
    the next start would do anyway. It keeps its @SPEC: the spec is the
    contract whether or not the function is published.

  * `install/2..5` is documented as what it is. One @doc covers every
    arity of a clause with defaults, so silence about the extra four
    would leave a test seam reading as an API.

  * Everything else is a command an operator invokes, and is documented
    with that framing rather than hidden - `upgradable/0` included,
    since the state it reports is invisible otherwise and a diagnostic
    nobody is told about is one nobody thinks to ask.

The specs say `:: :ok` and nothing more, because that is the whole of
what `report!/1` returns. `mix docs` is clean; its one complaint was a
reference to `Kernel.CLI`, which is hidden, so `Castle.Error`'s own
wording is used instead.

Three internal notes had gone stale and are corrected with it: two named
a `commit/3` that is now `commit/5`, and one claimed `commit` still
composes materialisation outside the serialised region, which castle#14
ended.

Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01C4oaMvbR1cbxrZBj8qwkqN

Two claims a review caught, both the same shape as the seven before them:
a qualification applied in one place and not the neighbouring one.

unpack/1 said the tarball has to be copied into the deployment's releases
directory. release_handler reads whichever directory RELDIR or the sasl
releases_dir parameter names - do_unpack_release joins RelDir, and RelDir is
that override when it is set - so an operator following it on such a
deployment copies the archive somewhere unpack will not look. The
release-record file already carried this caveat two @docs away.
customize/1's :tar warning repeated the same unqualified path and now points
at unpack/1 for it.

And AGENTS.md still said a failure raises Castle.Error three paragraphs after
the rule correcting exactly that. installed/5 re-raises an exception, throw or
exit out of install_release/1 unchanged, so a rescue narrowed to Castle.Error
misses a command that blew up rather than refused. Said as refusal rather than
failure, with a paragraph on why the blanket version keeps coming back. The
module comment on the boundary had it too.

Co-Authored-By: Claude <noreply@anthropic.com>

remove/1's doc said the command deletes erts-<vsn>, using the same vsn as its
release-version argument. do_remove_release/4 reads erts_vsn out of the
release record and removes erts-<EVsn> only when no remaining release refers
to that emulator - and the two numbers are unrelated, normally different ones:
a release at 0.1.1 may be carrying erts-16.2. So the doc named a directory
that generally does not exist.

The same placeholder was reused in five other places where it sits beside
lib/<app>-<vsn> and so reads as the same version, including the ERTS guard's
own refusal message, which ships. All now say erts-<erts_vsn>. The synthetic
release fixture's erts-<vsn>/bin is left alone: there is no adjacent
lib/<app>-<vsn> and the version genuinely is the emulator's.

The whole-message assertion in erts_guard_test failed on the reword, which is
what it is for - the message has been wrong three times about what it can
claim, so changing it deliberately means editing that test deliberately.

Co-Authored-By: Claude <noreply@anthropic.com>

AGENTS.md already quoted do_remove_release/4 deleting filename:join(Root,
"erts-" ++ EVsn) correctly; the drift was in the placeholder prose around it,
which reused <vsn> for both namespaces and so named a directory that generally
does not exist. Note it at the authority, with where it had already got to -
remove/1's @doc and the ERTS guard's refusal message, which ships.

Co-Authored-By: Claude <noreply@anthropic.com>

…laim

Two claims a review found, both asserting more than the code does.

The unpack doc offered RELDIR and the sasl releases_dir parameter as ways to
name another release directory. rel_dir/0 is Path.join(Deployment.root_dir(),
"releases") and consults neither, so setting one does not merely go unread: it
moves the directory the handler unpacks into and keeps its records in, while
the ERTS guard reading the target .rel (commands.ex:128) and the step writing
the target configuration (commands.ex:743) both still resolve
<root>/releases/<vsn>. The doc was directing operators into an upgrade that
cannot complete. It now says so. AGENTS.md already had this right and cites
issue #23; the omission was only in the public doc.

The moduledoc said the commands that are questions "succeed with nothing to
say at all". releases/0 is a question and prints a line per release through
report!/1, which its own @doc promises, so automation was given the wrong
stdout contract. What gets printed varies by command, not by kind:
upgradable/0 and running/1 return {:ok, []}, releases/0 returns the table.

Co-Authored-By: Claude <noreply@anthropic.com>

The passage explaining what is published and what is hidden named two
exceptions and then said every other function is a command an operator
invokes. running/1 is not: bin/castle dispatches exactly releases,
upgradable, unpack, install, remove and commit, and running/1 has no
subcommand - its only shipped caller is the confirmation loop inside
bin/castle install. Its own new @doc says so, so AGENTS.md contradicted the
file it is describing.

It stays published, but for a different reason than the other two: it answers
a read-only question and mutates nothing, and automation driving rpc rather
than bin/castle needs it to know when an install has finished booting. That is
the distinction from make_releases/0, which mutates bookkeeping once and is
useless by hand.

Co-Authored-By: Claude <noreply@anthropic.com>

The previous commit overcorrected. Fixing a paragraph that offered RELDIR and
the sasl releases_dir parameter as supported, it also asserted that
<root>/releases is the only release directory Castle resolves - which is wrong
about the tarball, the one thing the paragraph exists to locate. unpack/1 hands
the name straight to :release_handler.unpack_release/1 and joins nothing;
do_unpack_release/4 does Tar = filename:join(RelDir, ReleaseName ++ ".tar.gz")
against the handler own releases directory, which the overrides move. An
operator following the text would have failed at the unpack step.

The text now separates the two halves: the tarball goes where the handler
reads it, and the overrides move that; everything Castle resolves for itself
is joined onto code:root_dir(), so an override still leaves the halves
disagreeing and an unpack that succeeds is followed by an install that cannot.
The unsupported warning and the #23 reference stay.

Also corrects a claim the previous commit made in passing, in its message and
its prose: commands.ex:128 is in create_releases/3, on the make_releases/0
path, not in the ERTS guard. The install-side consumers of Castle rel_dir are
restart_planned?/3, unclaimed/3, materialise/3, arm/4 and installed/5.

Co-Authored-By: Claude <noreply@anthropic.com>